
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>指令 - vue.js</title>
        <meta charset="utf-8">
        <meta name="description" content="Vue.js - Intuitive, Fast and Composable MVVM for building interactive interfaces.">
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
        <!-- <link href='http://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600|Source+Code+Pro|Dosis:300,500' rel='stylesheet' type='text/css'> -->
        <link rel="icon" href="/images/logo.png" type="image/x-icon">
        <script>
            window.PAGE_TYPE = "api"
        </script>
        <link rel="stylesheet" href="/css/page.css" type="text/css">
        <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-46852172-1', 'vuejs.org');
  ga('send', 'pageview');
</script>
        <script src="/js/vue.js"></script>
    </head>
    <body>
        <div id="mobile-bar">
            <a class="menu-button"></a>
            <a class="logo" href="/"></a>
        </div>
        
            <div id="header">
    <a id="logo" href="/">
        <img src="/images/logo.png">
        <span>Vue.js</span>
    </a>
    <ul id="nav">
        <li>
  <form id="search-form">
    <input type="text" id="search-query" class="st-default-search-input">
  </form>
</li>
<li><a href="/guide/" class="nav-link">教程</a></li>
<li><a href="/api/" class="nav-link current">API</a></li>
<li><a href="/examples/" class="nav-link">示例</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>

    </ul>
</div>
            <div id="main">
                
                    
    <div class="sidebar">
    <ul class="main-menu">
        <li>
  <form id="search-form">
    <input type="text" id="search-query" class="st-default-search-input">
  </form>
</li>
<li><a href="/guide/" class="nav-link">教程</a></li>
<li><a href="/api/" class="nav-link current">API</a></li>
<li><a href="/examples/" class="nav-link">示例</a></li>
<li><a href="/blog/" class="nav-link">Blog</a></li>
<li><a href="https://github.com/yyx990803/vue" target="_blank" class="nav-link">GitHub</a></li>

    </ul>
    <div class="list">
        <h2>Api</h2>
        <ul class="menu-root">
            
                <li>
                    <a href="/api/index.html" class="sidebar-link">概述</a>
                </li>
            
                <li>
                    <a href="/api/options.html" class="sidebar-link">组件选项</a>
                </li>
            
                <li>
                    <a href="/api/instance-properties.html" class="sidebar-link">实例属性</a>
                </li>
            
                <li>
                    <a href="/api/instance-methods.html" class="sidebar-link">实例方法</a>
                </li>
            
                <li>
                    <a href="/api/global-api.html" class="sidebar-link">全局 API</a>
                </li>
            
                <li>
                    <a href="/api/directives.html" class="sidebar-link current">指令</a>
                </li>
            
                <li>
                    <a href="/api/filters.html" class="sidebar-link">过滤器</a>
                </li>
            
                <li>
                    <a href="/api/elements.html" class="sidebar-link new">特殊元素</a>
                </li>
            
            <li><a href="http://legacy.vuejs.org">旧版 0.11 文档</a></li>
            <li style="margin:10px 0 3px">
              <script data-gittip-username="yyx990803"
                data-gittip-widget="button"
                src="//gttp.co/v1.js"></script>
            </li>
        </ul>
    </div>
</div>


<div class="content api with-sidebar">
    <h1>指令</h1>
    <div id="ad">
        <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=vuejs" id="_carbonads_js"></script>
    </div>
    <h2 id="响应式指令">响应式指令</h2><blockquote>
<p>指令可以将自己与一个 Vue 实例上的属性绑定，也可以与一个实例作用域中的表达式绑定。当属性或表达式的值发生改变时，指令的 <code>update()</code> 方法会在下一个事件循环中被异步调用。</p>
</blockquote>
<h3 id="v-text">v-text</h3><p>更新元素的 <code>textContent</code>。</p>
<p>{&#123; Mustache &#125;} 的插值也会被当做文字节点上的 <code>v-text</code> 指令进行编译。</p>
<h3 id="v-html">v-html</h3><p>更新元素的 <code>innerHTML</code>。</p>
<p>将 <code>v-html</code> 绑定到用户提供的数据上会有 XSS 的风险，因此使用 <code>v-html</code> 时应确保数据的安全性，或通过自定义过滤器将不被信任的 HTML 内容进行预处理。</p>
<h3 id="v-show">v-show</h3><ul>
<li>可触发过渡效果。</li>
</ul>
<p>根据绑定值将元素的 display CSS 属性设置为 <code>none</code> 或它的原始值。</p>
<h3 id="v-class">v-class</h3><ul>
<li>接受一个可选的参数</li>
</ul>
<p>如果没有提供参数，则将绑定值作为 CSS 类命字符串添加到元素的 classList 中。</p>
<p>如果提供了参数，则会以参数为 CSS 类名，并根据绑定值的真伪进行切换。可以配合多重从句使用：</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">span</span> <span class="attribute">v-class</span>=<span class="value">"</span><br><span class="line">  red    : hasError,</span><br><span class="line">  bold   : isImportant,</span><br><span class="line">  hidden : isHidden</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">span</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>或者，你可以直接将该指令绑定到一个对象。对象的键值会作为类名被添加到元素的 classList，并根据对应值的真伪切换。</p>
<h3 id="v-attr">v-attr</h3><ul>
<li>需要一个参数</li>
</ul>
<p>更新元素的指定特性（由参数指定）</p>
<p><strong>示例:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">canvas</span> <span class="attribute">v-attr</span>=<span class="value">"width:w, height:h"</span>&gt;</span><span class="tag">&lt;/<span class="title">canvas</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>除 0 外的其他伪值将移除该特性。</p>
<p>或者，你可以直接将该指令绑定到一个对象。对象的键会被作为特性名称，根据对应的值的真伪进行切换。</p>
<p>在内部，普通特性中的 {&#123; Mustache &#125;} 插值会被转换为 <code>v-attr</code> 指令进行编译。</p>
<p>从 0.12.9 开始，当 <code>v-attr</code> 直接用在 <code>&lt;input&gt;</code> 元素的 <code>value</code> 特性中时，实际设置的会是其 <code>value</code> 属性 (property) 而不是特性 (attribute)。例如，<code>&lt;input value=&quot;{{val}}&quot;&gt;</code> 不会更新其特性值，而是会直接设置其属性值。</p>
<p class="tip">在为 <code>&lt;img&gt;</code> 元素设置 <code>src</code> 特性时，应该使用 <code>v-attr</code> 绑定而不是 mustache 模板绑定。浏览器会先于 Vue.js 对你的模板进行解析。所以当浏览器试图获取图片 URL 时，使用 mustache 模板绑定的数据会导致 404 错误。</p>

<h3 id="v-style">v-style</h3><ul>
<li>接受一个可选参数</li>
</ul>
<p>为元素添加内联 CSS 样式。</p>
<p>如果没有参数名，绑定值可以是一个字符串或是一个对象。</p>
<ul>
<li>如果绑定值为字符串，则会将该元素的 <code>style.cssText</code> 属性设置为参数的值。</li>
<li>如果绑定值为对象，对象里的每一对键值都将被赋值到元素的 style 对象上。</li>
</ul>
<p><strong>示例:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"myStyles"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<figure class="highlight js"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">// myStyles 可以是字符串:</span></span><br><span class="line"><span class="string">"color:red; font-weight:bold;"</span></span><br><span class="line"><span class="comment">// 也可以是对象:</span></span><br><span class="line">&#123;</span><br><span class="line">  color: <span class="string">'red'</span>,</span><br><span class="line">  <span class="comment">// CSS 规则用驼峰格式和连字符格式都可以</span></span><br><span class="line">  fontWeight: <span class="string">'bold'</span>,</span><br><span class="line">  <span class="string">'font-size'</span>: <span class="string">'2em'</span></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>
<p>如果有参数的话，参数会被当作 CSS 规则名来用。可以配合多重从句添加多条规则：</p>
<p><strong>示例:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"</span><br><span class="line">  top: top + 'px',</span><br><span class="line">  left: left + 'px',</span><br><span class="line">  background-color: 'rgb(0,0,' + bg + ')'</span><br><span class="line">"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p><code>v-style</code> 会智能地检测 CSS 规则是否需要浏览器前缀，所以你可以放心的使用无前缀版本的 CSS 规则。</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!-- 如果需要的话会自动使用 -webkit-transform --&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">v-style</span>=<span class="value">"transform: 'scale(' + scale + ')'"</span>&gt;</span><span class="tag">&lt;/<span class="title">div</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p class="tip">由于 IE 的所有版本都会在解析 HTML 时将无法解析的内联样式删除，因此推荐统一使用 <code>v-style</code> 指令来代替 style 特性中的 &#123;&#123;mustache&#125;&#125; 插值。</p>

<h3 id="v-on">v-on</h3><ul>
<li>需要一个参数。</li>
<li>绑定值应该是一个函数或者声明。</li>
</ul>
<p>为元素添加一个 DOM 事件监听器。事件的类型由参数指定。这也是唯一可以和 <code>key</code> 过滤器一起使用的指令。详细请见<a href="../guide/events.html">事件监听</a>。</p>
<h3 id="v-model">v-model</h3><ul>
<li>只能用于 <code>&lt;input&gt;</code>, <code>&lt;select&gt;</code> 或 <code>&lt;textarea&gt;</code> 元素。</li>
<li>指令特性参数: <a href="/guide/forms.html#惰性更新"><code>lazy</code></a>, <a href="/guide/forms.html#转换为数字"><code>number</code></a>, <a href="/guide/forms.html#动态_select_选项"><code>options</code></a>, <a href="/guide/forms.html#输入_Debounce"><code>debounce</code></a></li>
</ul>
<p>在表单 input 元素上创建一个双向绑定。默认在 input 事件时同步数据。详情请见<a href="../guide/forms.html">处理表单</a>.</p>
<h3 id="v-if">v-if</h3><ul>
<li>可触发过渡效果。</li>
</ul>
<p>基于绑定值的真伪，插入或移除元素。如果元素为 <code>&lt;template&gt;</code> 元素，则它的内容将会被提取出来作为被插入或移除的片段。</p>
<p><strong>示例:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">template</span> <span class="attribute">v-if</span>=<span class="value">"test"</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">template</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>渲染结果:</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="comment">&lt;!--v-if-start--&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>hello<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;<span class="title">p</span>&gt;</span>world<span class="tag">&lt;/<span class="title">p</span>&gt;</span></span><br><span class="line"><span class="comment">&lt;!--v-if-end--&gt;</span></span><br></pre></td></tr></table></figure>
<h3 id="v-repeat">v-repeat</h3><ul>
<li>会创建子 Vue 实例。</li>
<li>绑定值应为一个数组、对象或数字。</li>
<li>可触发过渡效果。</li>
<li>接受一个可选参数。</li>
<li>指令特性参数：<a href="/guide/list.html#使用_track-by"><code>track-by</code></a>, <a href="/guide/transitions.html#渐进过渡效果"><code>stagger</code></a>, <a href="/guide/transitions.html#渐进过渡效果"><code>enter-stagger</code></a>, <a href="/guide/transitions.html#渐进过渡效果"><code>leave-stagger</code></a></li>
</ul>
<p>为绑定的数组或对象中的每一项创建一个子 ViewModel 实例。如果值是一个数字，则会创建对应数量的子实例。当数组或对象的可变方法 (mutating method) 比如 <code>push()</code> 被调用，或是绑定的数字变化时，相应的子实例都会自动被创建或删除。</p>
<p>如果没有提供参数，子实例会直接使用数组内分配的元素作为其 <code>$data</code>。如果值不是一个对象，则会将其作为 <code>$value</code> 直接存放在实例上。</p>
<p><strong>示例:</strong></p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;name&#125;&#125; &#123;&#123;email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>如果提供了参数，则总是会创建一个数据包装对象，用参数字符串作为键名来存放原本的数据对象。别名参数可以使得模板中的数据访问更加清晰：</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"user : users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;user.name&#125;&#125; &#123;&#123;user.email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>0.12.8 引入了一种更自然的别名语法：</p>
<figure class="highlight html"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="tag">&lt;<span class="title">ul</span>&gt;</span></span><br><span class="line">  <span class="tag">&lt;<span class="title">li</span> <span class="attribute">v-repeat</span>=<span class="value">"user in users"</span>&gt;</span></span><br><span class="line">    &#123;&#123;user.name&#125;&#125; &#123;&#123;user.email&#125;&#125;</span><br><span class="line">  <span class="tag">&lt;/<span class="title">li</span>&gt;</span></span><br><span class="line"><span class="tag">&lt;/<span class="title">ul</span>&gt;</span></span><br></pre></td></tr></table></figure>
<p>更多详细示例，请参看<a href="../guide/list.html">列表渲染</a>.</p>
<h2 id="字面指令">字面指令</h2><blockquote>
<p>字面指令将它们的特性值视为纯字符串，不会视图建立数据绑定。它们只负责调用 <code>bind()</code>函数一次。字面指令的值也可以包含 mustache 表达式插值，具体的处理方式请参考<a href="/guide/custom-directive.html#动态字面指令">动态字面指令</a>。</p>
</blockquote>
<h3 id="v-transition">v-transition</h3><ul>
<li>可以响应 Mustaches 插值</li>
</ul>
<p>通知 Vue.js 为元素应用过渡效果。当一个可以触发过渡效果的指令将元素插入或移除时，或是当 Vue 实例中操作 DOM 的方法被调用时，对应的过渡效果就会被应用到该元素上。</p>
<p>详情请见<a href="/guide/transitions.html">过渡系统</a>。</p>
<h3 id="v-ref">v-ref</h3><p>在父组件上注册一个引用到子组件，便于访问只能和组件或是 <code>v-repeat</code> 协同使用。注册之后，父级的 <code>$</code> 对象上可以访问注册的子实例。示例见<a href="../guide/components.html#子组件引用">子组件引用</a>.</p>
<p>当该指令与 <code>v-repeat</code> 一起使用时，<code>v-ref</code> 注册的值将会是一个包含了所有子实例的数组，这个数组与 <code>v-repeat</code> 绑定的数组是相对应的。</p>
<p>如果 <code>v-repeat</code> 的源数据是一个对象，则 <code>v-ref</code> 注册的值会是一个对象，按照键值包含对应的子实例。</p>
<h3 id="v-el">v-el</h3><p>在 Vue 实例的 <code>$$</code> 对象里注册一个 DOM 元素的引用。比如 <code>&lt;div v-el=&quot;hi&quot;&gt;</code> 可以使用<code>vm.$$.hi</code> 获取。</p>
<h2 id="空指令">空指令</h2><blockquote>
<p>空指令不需要参数，并且会忽略它的特性值。</p>
</blockquote>
<h3 id="v-pre">v-pre</h3><p>跳过编译此元素和此元素所有的子元素。跳过大量没有指令的节点可以加快编译速度。</p>
<h3 id="v-cloak">v-cloak</h3><p>直到关联的 ViewModel 结束编译之前本属性都会留在元素上。与 <code>[v-cloak] { display: none }</code> 类似的样式结合，这个指令可以用来在 ViewModel 准备好之前隐藏没有被编译的 &#123;&#123; Mustache &#125;&#125; 模板。</p>

    <div class="footer">发现了问题或想要贡献？来 Github 给 Vue.js <a href="https://github.com/vuejs/vuejs.org" target="_blank">英文站点</a>或<a href="https://github.com/Jinjiang/vuejs.org/tree/lang-zh" target="_blank">中文翻译</a>来个 Fork 吧！</div>
</div>
                
            </div>
            <script src="/js/smooth-scroll.min.js"></script>
            <script src="/js/common.js"></script>
        

        <script src="https://cdnjs.cloudflare.com/ajax/libs/fastclick/1.0.6/fastclick.min.js"></script><script src="https://cdn.jsdelivr.net/gh/shentao/vuejs-outdated-docs-modal@v1.3/prompt.min.js"></script>
        <script>
            document.addEventListener('DOMContentLoaded', function() {
                FastClick.attach(document.body);
            }, false);
        </script>
    </body>
</html>
